a11y: Document roles of widgets

Add a section to the long description for each
widget that is using a non-default accessible role.

diff --git a/gtk/gtkbutton.c b/gtk/gtkbutton.c
index 173d4e8bf115c88a4b8f55a9802b71218d19faf6..d85d65ca484b6be6b4ea98fd983824f4ec880706 100644 (file)
--- a/gtk/gtkbutton.c
+++ b/gtk/gtkbutton.c
@@ -49,6 +49,10 @@
  * #GtkLockButton, #GtkColorButton or #GtkFontButton use style classes such as
  * .toggle, .popup, .scale, .lock, .color on the button node
  * to differentiate themselves from a plain GtkButton.
+ *
+ * # Accessibility
+ *
+ * GtkButton uses the #GTK_ACCESSIBLE_ROLE_BUTTON role.
  */
 
 #include "config.h"

diff --git a/gtk/gtkcheckbutton.c b/gtk/gtkcheckbutton.c
index 82e2fd5963a6b213f40d75e38eb06a42d952d301..802355d9d44575afb57bfab595ce5ff550ba9823 100644 (file)
--- a/gtk/gtkcheckbutton.c
+++ b/gtk/gtkcheckbutton.c
@@ -73,6 +73,10 @@
  * A GtkCheckButton without indicator changes the name of its main node
  * to button and adds a .check style class to it. The subnode is invisible
  * in this case.
+ *
+ * # Accessibility
+ *
+ * GtkCheckButton uses the #GTK_ACCESSIBLE_ROLE_CHECKBOX role.
  */
 
 typedef struct {

diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index 40a5e159b01a2e3b6fdb640675fdd48f4232df4b..9c1f05436eeb73148a71100d90d21ccc009304b8 100644 (file)
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -157,6 +157,10 @@
  *   </action-widgets>
  * </object>
  * ]|
+ *
+ * # Accessibility
+ *
+ * GtkDialog uses the #GTK_ACCESSIBLE_ROLE_DIALOG role.
  */
 
 typedef struct _ResponseData ResponseData;

diff --git a/gtk/gtkprogressbar.c b/gtk/gtkprogressbar.c
index 1041e1185fbaa6b03c836fc7f0586de826f4babd..6255296ea93aefa30c00bb28a10af8b3cc8b1b71 100644 (file)
--- a/gtk/gtkprogressbar.c
+++ b/gtk/gtkprogressbar.c
@@ -85,6 +85,10 @@
  * .right, .top or .bottom added when the progress 'touches' the corresponding
  * end of the GtkProgressBar. The .osd class on the progressbar node is for use
  * in overlays like the one Epiphany has for page loading progress.
+ *
+ * # Accessibility
+ *
+ * GtkProgressBar uses the #GTK_ACCESSIBLE_ROLE_PROGRESS_BAR role.
  */
 
 typedef struct _GtkProgressBarClass         GtkProgressBarClass;

diff --git a/gtk/gtkradiobutton.c b/gtk/gtkradiobutton.c
index 5a73b8ce368542fac803639b12537b8f5f314eb9..a986f3cc89f9a0e852299b81a2c6b48bfe771f7d 100644 (file)
--- a/gtk/gtkradiobutton.c
+++ b/gtk/gtkradiobutton.c
@@ -69,27 +69,6 @@
  * The group list does not need to be freed, as each #GtkRadioButton will remove
  * itself and its list item when it is destroyed.
  *
- * # CSS nodes
- *
- * |[<!-- language="plain" -->
- * radiobutton
- * ├── radio
- * ╰── <child>
- * ]|
- *
- * A GtkRadioButton with indicator (see gtk_check_button_set_draw_indicator())) has a
- * main CSS node with name radiobutton and a subnode with name radio.
- *
- * |[<!-- language="plain" -->
- * button.radio
- * ├── radio
- * ╰── <child>
- * ]|
- *
- * A GtkRadioButton without indicator changes the name of its main node
- * to button and adds a .radio style class to it. The subnode is invisible
- * in this case.
- *
  * ## How to create a group of two radio buttons.
  *
  * |[<!-- language="C" -->
@@ -124,6 +103,31 @@
  * selected button.
  * Inside the #GtkToggleButton::toggled handler, gtk_toggle_button_get_active()
  * can be used to determine if the button has been selected or deselected.
+ *
+ * # CSS nodes
+ *
+ * |[<!-- language="plain" -->
+ * radiobutton
+ * ├── radio
+ * ╰── <child>
+ * ]|
+ *
+ * A GtkRadioButton with indicator (see gtk_check_button_set_draw_indicator())) has a
+ * main CSS node with name radiobutton and a subnode with name radio.
+ *
+ * |[<!-- language="plain" -->
+ * button.radio
+ * ├── radio
+ * ╰── <child>
+ * ]|
+ *
+ * A GtkRadioButton without indicator changes the name of its main node
+ * to button and adds a .radio style class to it. The subnode is invisible
+ * in this case.
+ *
+ * # Accessibility
+ *
+ * GtkRadioButton uses the #GTK_ACCESSIBLE_ROLE_RADIO role.
  */
 
 typedef struct _GtkRadioButtonClass         GtkRadioButtonClass;

diff --git a/gtk/gtkscale.c b/gtk/gtkscale.c
index ed8316ade6489e8641a933fb166e0f1c9c99ed3f..4317ac2baa40cd92b4b56587c230d91487a70698 100644 (file)
--- a/gtk/gtkscale.c
+++ b/gtk/gtkscale.c
@@ -125,6 +125,10 @@
  * If the scale is displaying the value (see #GtkScale:draw-value), there is
  * subnode with name value. This node will get the .top or .bottom style classes
  * similar to the marks node.
+ *
+ * # Accessibility
+ *
+ * GtkScale uses the #GTK_ACCESSIBLE_ROLE_SLIDER role.
  */
 
 

diff --git a/gtk/gtkscrollbar.c b/gtk/gtkscrollbar.c
index 25dd7ff9cb9c19f795f98368da7cf65cdd511237..ceae0caae8c031f573f789bffabf5ebd7f1eb5e5 100644 (file)
--- a/gtk/gtkscrollbar.c
+++ b/gtk/gtkscrollbar.c
@@ -78,6 +78,10 @@
  * Other style classes that may be added to scrollbars inside #GtkScrolledWindow
  * include the positional classes (.left, .right, .top, .bottom) and style
  * classes related to overlay scrolling (.overlay-indicator, .dragging, .hovering).
+ *
+ * # Accessibility
+ *
+ * GtkScrollbar uses the #GTK_ACCESSIBLE_ROLE_SCROLLBAR role.
  */
 
 typedef struct _GtkScrollbarClass   GtkScrollbarClass;

diff --git a/gtk/gtkseparator.c b/gtk/gtkseparator.c
index 63ad8380270e47e4dca4552ed6f6c89892996e52..fe9ac5843765f73ad1e5e5226a4cfeaa14054d2b 100644 (file)
--- a/gtk/gtkseparator.c
+++ b/gtk/gtkseparator.c
@@ -46,6 +46,10 @@
  *
  * GtkSeparator has a single CSS node with name separator. The node
  * gets one of the .horizontal or .vertical style classes.
+ *
+ * # Accessibility
+ *
+ * GtkSeparator uses the #GTK_ACCESSIBLE_ROLE_SEPARATOR role.
  */
 
 typedef struct _GtkSeparatorClass GtkSeparatorClass;

diff --git a/gtk/gtkspinbutton.c b/gtk/gtkspinbutton.c
index f008fac0044a121588bf6502184bdf2df4073a2f..d6517459cbd2598f85b61848b64582db0e70366e 100644 (file)
--- a/gtk/gtkspinbutton.c
+++ b/gtk/gtkspinbutton.c
@@ -90,32 +90,6 @@
  * not desired, the automatic sizing can be turned off by explicitly
  * setting #GtkSpinButton::width-chars to a value != -1.
  *
- * # CSS nodes
- *
- * |[<!-- language="plain" -->
- * spinbutton.horizontal
- * ├── text
- * │    ├── undershoot.left
- * │    ╰── undershoot.right
- * ├── button.down
- * ╰── button.up
- * ]|
- *
- * |[<!-- language="plain" -->
- * spinbutton.vertical
- * ├── button.up
- * ├── text
- * │    ├── undershoot.left
- * │    ╰── undershoot.right
- * ╰── button.down
- * ]|
- *
- * GtkSpinButtons main CSS node has the name spinbutton. It creates subnodes
- * for the entry and the two buttons, with these names. The button nodes have
- * the style classes .up and .down. The GtkText subnodes (if present) are put
- * below the text node. The orientation of the spin button is reflected in
- * the .vertical or .horizontal style class on the main node.
- *
  * ## Using a GtkSpinButton to get an integer
  *
  * |[<!-- language="C" -->
@@ -178,6 +152,36 @@
  *   gtk_widget_show (window);
  * }
  * ]|
+ *
+ * # CSS nodes
+ *
+ * |[<!-- language="plain" -->
+ * spinbutton.horizontal
+ * ├── text
+ * │    ├── undershoot.left
+ * │    ╰── undershoot.right
+ * ├── button.down
+ * ╰── button.up
+ * ]|
+ *
+ * |[<!-- language="plain" -->
+ * spinbutton.vertical
+ * ├── button.up
+ * ├── text
+ * │    ├── undershoot.left
+ * │    ╰── undershoot.right
+ * ╰── button.down
+ * ]|
+ *
+ * GtkSpinButtons main CSS node has the name spinbutton. It creates subnodes
+ * for the entry and the two buttons, with these names. The button nodes have
+ * the style classes .up and .down. The GtkText subnodes (if present) are put
+ * below the text node. The orientation of the spin button is reflected in
+ * the .vertical or .horizontal style class on the main node.
+ *
+ * # Accessiblity
+ *
+ * GtkSpinButton uses the #GTK_ACCESSIBLE_ROLE_SPIN_BUTTON role.
  */
 
 typedef struct _GtkSpinButton      GtkSpinButton;

diff --git a/gtk/gtkswitch.c b/gtk/gtkswitch.c
index 9e4aff1bcba6f1abc10c7736bd1b84605d62ec05..f4cc9f36152922822aa20cf10ce9db4b705fa06b 100644 (file)
--- a/gtk/gtkswitch.c
+++ b/gtk/gtkswitch.c
@@ -47,6 +47,10 @@
  *
  * GtkSwitch has four css nodes, the main node with the name switch and subnodes
  * for the slider and the on and off labels. Neither of them is using any style classes.
+ *
+ * # Accessibility
+ *
+ * GtkSwitch uses the #GTK_ACCESSIBLE_ROLE_SWITCH role.
  */
 
 #include "config.h"